Skip to main content
POST
/
toptimize
/
v1
/
predictions
[Beta] Add Quality Score
curl --request POST \
  --url https://api.topsort.com/toptimize/v1/predictions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metrics": {
    "ctr": true
  },
  "opaqueUserId": "u_9ske45",
  "productIds": [
    "p_PJbnN",
    "p_ojng4"
  ],
  "objectType": "listings"
}'
{
  "objectType": "listings",
  "predictions": [
    {
      "productId": "p_PJbnN",
      "ctr": 0.03,
      "cvr": 0.06
    },
    {
      "productId": "p_ojng4",
      "ctr": 0.056,
      "cvr": 0.091
    }
  ]
}

Authorizations

​
Authorization
string
header
required

A valid API key generated in Topsort's UI.

Body

application/json

⚠️ Beta Access Required Contact your sales representative to gain access to this endpoint and start using it. The context information for the predictions, including which metrics to predict.

Request to predict the outcome of an interaction.

​
metrics
object
required

Metrics to predict, the response will include all the selected metrics.

​
opaqueUserId
string
required

The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests.

Examples:

"71303ce0-de89-496d-8270-6434589615e8"

​
objectType
enum<string>
required

The type of object that is being reported on the interaction.

Available options:
listings,
banners
​
productIds
string[]
required
​
page
object

Information about the page where an auction or event occurs.

​
deviceType
enum<string>

The device the user is on.

Available options:
desktop,
mobile
Examples:

"mobile"

Response

The prediction results. This will provide a numerical value for each combination of metric/product requested on the API call.

The result of a prediction request, containing CTR and CVR predictions for products.

​
objectType
enum<string>
required

The type of object that was predicted.

Available options:
listings,
banners
Examples:

"listings"

​
predictions
object[]
required

Predicted objects

Examples:
[
  {
    "productId": "product-123",
    "ctr": 0.05,
    "cvr": 0.101
  }
]